---
title: Popover
description: A popover is an overlay element positioned relative to a trigger.
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/Popover.html
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/overlays/popover.mdx?plain=1
---

{/* prettier-ignore-start */}

<Alert><span className="font-bold">Note:</span> Popover only provides the overlay itself. It should be combined with Dialog to create fully accessible popover dialogs. <Link href="/docs/components/overlays/dialog">See dialog</Link> component instead.</Alert>

{/* prettier-ignore-end */}

<ComponentPreview name="popover/demos/basic" preview={``} />

## Installation

```package-install
npx shadcn@latest add @dotui/popover
```

## API Reference

| Prop                           | Type                                                                                                                                                                                                                                                                                                                     | Default         | Description                                                                                                                                                                                                                                                                                                     |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placement`                    | `'bottom' \| 'bottom left' \| 'bottom right' \| 'bottom start' \| 'bottom end' \| 'top' \| 'top left' \| 'top right' \| 'top start' \| 'top end' \| 'left' \| 'left top' \| 'left bottom' \| 'start' \| 'start top' \| 'start bottom' \| 'right' \| 'right top' \| 'right bottom' \| 'end' \| 'end top' \| 'end bottom'` | `'bottom'`      | The placement of the element with respect to its anchor element.                                                                                                                                                                                                                                                |
| `offset`                       | `number`                                                                                                                                                                                                                                                                                                                 | `8`             | The additional offset applied along the main axis between the element and its anchor element.                                                                                                                                                                                                                   |
| `crossOffset`                  | `number`                                                                                                                                                                                                                                                                                                                 | `0`             | The additional offset applied along the cross axis between the element and its anchor element.                                                                                                                                                                                                                  |
| `containerPadding`             | `number`                                                                                                                                                                                                                                                                                                                 | `12`            | The placement padding that should be applied between the element and its surrounding container.                                                                                                                                                                                                                 |
| `shouldFlip`                   | `boolean`                                                                                                                                                                                                                                                                                                                | `true`          | Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.                                                                                                                                                              |
| `isOpen`                       | `boolean`                                                                                                                                                                                                                                                                                                                | -               | Whether the overlay is open by default (controlled).                                                                                                                                                                                                                                                            |
| `defaultOpen`                  | `boolean`                                                                                                                                                                                                                                                                                                                | -               | Whether the overlay is open by default (uncontrolled).                                                                                                                                                                                                                                                          |
| `isDismissable`                | `boolean`                                                                                                                                                                                                                                                                                                                | `false`         | Whether to close the modal when the user interacts outside it.                                                                                                                                                                                                                                                  |
| `UNSTABLE_portalContainer`     | `Element`                                                                                                                                                                                                                                                                                                                | `document.body` | The container element in which the overlay portal will be placed. This may have unknown behavior depending on where it is portalled to.                                                                                                                                                                         |
| `isKeyboardDismissDisabled`    | `boolean`                                                                                                                                                                                                                                                                                                                | `false`         | Whether pressing the escape key to close the dialog should be disabled.                                                                                                                                                                                                                                         |
| `shouldCloseOnInteractOutside` | `(element: Element) => boolean`                                                                                                                                                                                                                                                                                          | -               | When user interacts with the argument element outside of the overlay ref, return `true` if `onClose` should be called. This gives you a chance to filter out interaction with elements that should not dismiss the overlay. By default, `onClose` will always be called on interaction outside the overlay ref. |
| `children`                     | `ReactNode \| (opts: PopoverRenderProps) => ReactNode`                                                                                                                                                                                                                                                                   | -               | The children of the component. A function may be provided to alter the children based on component state.                                                                                                                                                                                                       |
| `className`                    | `string \| (values: PopoverRenderProps & {defaultClassName: string \| undefined}) => string`                                                                                                                                                                                                                             | -               | The CSS className for the element. A function may be provided to compute the class based on component state.                                                                                                                                                                                                    |
| `style`                        | `CSSProperties \| (values: PopoverRenderProps & {defaultStyle: CSSProperties}) => CSSProperties \| undefined`                                                                                                                                                                                                            | -               | The inline style for the element. A function may be provided to compute the style based on component state.                                                                                                                                                                                                     |

| Event          | Type                        | Description                                                   |
| -------------- | --------------------------- | ------------------------------------------------------------- |
| `onOpenChange` | `(isOpen: boolean) => void` | Handler that is called when the overlay's open state changes. |
